'\" t
.\"     Title: dictionary
.\"    Author: Alan DeKok
.\" Generator: Asciidoctor 2.0.23
.\"      Date: 2025-05-04
.\"    Manual: FreeRADIUS
.\"    Source: FreeRADIUS
.\"  Language: English
.\"
.TH "DICTIONARY" "5" "2025-05-04" "FreeRADIUS" "FreeRADIUS"
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.ss \n[.ss] 0
.nh
.ad l
.de URL
\fI\\$2\fP <\\$1>\\$3
..
.als MTO URL
.if \n[.g] \{\
.  mso www.tmac
.  am URL
.    ad l
.  .
.  am MTO
.    ad l
.  .
.  LINKSTYLE blue R < >
.\}
.SH "NAME"
dictionary \- FreeRADIUS dictionary file
.SH "DICTIONARIES"
.sp
The \f(CRdictionary\fP files define names, numbers, and
data types for use in the server.  In general,
the dictionary files are defined by industry standard specifications,
or by a vendor for their own equipment.
.sp
Each dictionary file contains a list of protocol\-specific attributes
and values, which the server uses to map between descriptive names and
on\-the\-wire data.  The names have no meaning outside of the server,
and (with rare exception) are never sent "on the wire" between server
and clients.
.sp
That is, editing the dictionaries will have \fIno effect\fP on anything
other than the server that is reading those files.  Adding new
attributes to the dictionaries will have \fIno effect\fP on clients, and
will not make clients magically understand those attributes.  The
dictionaries are solely for local administrator convenience, and are
specific to each version of FreeRADIUS.
.sp
The dictionary files in the \f(CRshare\fP directory \fIshould not be edited\fP.
Editing those files will likely break the server.
.sp
Instead, you can add local dictionary definitions in the
raddb/dictionary file.
.SH "CONCEPTS AND BACKGROUND"
.sp
The dictionaries are necessary because many networking protocols do
not send humanly\-readable names over the network.  Instead, the
protocols send sequences of bytes to represent concepts, where each
byte has a particular meaning.
.sp
At the same time, it is useful for administrators to write policies
based on names, and not on numbers.  No one wants to write a policy of
the form \f(CRif concept 15 has value "foo", then do ...\fP.
.sp
The dictionaries solve this problem by enabling the server to decode
the magic numbers into humanly\-readable names.  The administrator can
then write policies of the form \f(CRif the User\-Name has value "bob",
then do something ...\fP.
.sp
Policies using descriptive are much simpler to create and understand
than policies using numbers.
.sp
The dictionaries also enable the server to decode protocols using
data types, and then present that decoded data
to the administrator.  As with the other examples above, it would be
very difficult write policies based on "raw hex" data: \f(CRif User\-Name is 0x626f62 ...\fP.
.sp
The dictionaries solve the data type problem by associating
data types with a name and number.  That way the
bytes \f(CR0x7f000001\fP can be presented to the administrator as an IPv4
address of \f(CR127.0.0.1\fP.
.sp
This association is two\-way, protocols can get decoded to
understandable names and data types, and those names and data can get
encoded in protocols.
.SS "Dictionaries are always local"
.sp
In almost all cases, the names defined in a dictionary have no meaning
outside of the server.  The names are never sent "on the wire" between
server and client.  Editing the dictionary names on one system will
\fInot change\fP the names used by another system.
.sp
The names are also local to each implementation.  FreeRADIUS has
chosen a set of names for itself, which are based on specifications
and on vendor definitions.  In nearly all cases, these names are
either the same as the external definition, or are very similar to the
external definition.
.sp
In general, the only reason for us to change the names is that the
names conflict with another name.  It is not possible to have the same
name mean two entirely different things.
.sp
Vendors can submit new dictionaries to us via
.MTO "dictionary\(atfreeradius.org" "email" ","
or via
.URL "https://github.com/FreeRADIUS/freeradius\-server/" "GitHub" "."
.SS "Names are Case\-insensitive"
.sp
When names are printed, they are printed as the name given in the
dictionaries.  When a name is looked up in the dictionaries, the
lookup is done in a case\-insensitive manner.
.SS "Names are Hierarchical"
.sp
In earlier versions of FreeRADIUS, the names were global.  The global
names for attributes caused issue with implementations, as noted in
\c
.URL "https://www.rfc\-editor.org/rfc/rfc6929.html#section\-2.7.1" "RFC 6929
Section 2.7.1" .  This limitation caused the names to be long, and have
"vendor prefixes", such as with \f(CRCisco\-AVPair\fP.
.sp
The names in FreeRADIUS are now hierarchical.  In most cases, the old
names are simply split into separate sub\-names with a period (\f(CR.\fP).
For example, the previously mentioned \f(CRCisco\-AVPair\fP now becomes
\f(CRCisco.AVPair.\fP, or \f(CRVendor\-Specific.Cisco.AVPair\fP.
.sp
If there is still a need to use the old names, the
ALIAS keyword can help.  See
\f(CRraddb/dictionary\fP for additional documentation.
.SS "Names matter, not definitions"
.sp
Names occur in many places, such as in
ATTRIBUTE definitions,
DEFINE,
MEMBER,
STRUCT, etc.  We generally refer to all
of these entities as being \*(Aqattributes\*(Aq, no matter how the name was
defined.
.SH "FILES AND LOCATION"
.sp
The dictionaries are placed into a \f(CRshare\fP directory, which is usually
in a location such as \f(CR/usr/share/freeradius/\fP.  The definitions for
each individual specification or vendor dictionary are placed in files
with the appropriate name.  For example, \f(CRdictionary.rfc2865\fP or
\f(CRdictionary.cisco\fP.
.sp
We reiterate that these dictionaries should not be edited.  These
dictionaries ship with the server, and any new installation (or
upgrade) will over\-write local changes.
.sp
Local edits should be kept to the \f(CRraddb/dictionary\fP file, which will
not be overwritten on an upgrade.
.SH "FILE SYNTAX"
.sp
The dictionary file format follows the standard RADIUS dictionary
syntax.  In many respects, the format has had only minor changes since
the original Livingston RADIUS server in 1993.
.sp
The file format is simple, and line\-oriented.  Blank lines are
ignored.  Hash (\f(CR#\fP) characters are comments, and cause everything
after the hash character to be ignored, up to the end of the line.
.sp
Every non\-blank line starts with a keyword, as given in the table
below.  In most cases, the main keywords of interest are
ATTRIBUTE and VALUE.
.sp
.it 1 an-trap
.nr an-no-space-flag 1
.nr an-break-flag 1
.br
.B Table 1. Dictionary Definition Keywords
.TS
allbox tab(:);
ltB ltB.
T{
.sp
Keyword
T}:T{
.sp
Description
T}
.T&
lt lt.
T{
.sp
ALIAS
T}:T{
.sp
Define a name which references an \f(CRATTRIBUTE\fP
T}
T{
.sp
ATTRIBUTE
T}:T{
.sp
Define a name, number, and data type mapping
T}
T{
.sp
DEFINE
T}:T{
.sp
Define a name and data type mapping
T}
T{
.sp
ENUM
T}:T{
.sp
Define a named enumeration of values for use with multiple \f(CRATTRIBUTE\fPs
T}
T{
.sp
FLAGS
T}:T{
.sp
Set flags for subsequent definitions
T}
T{
.sp
$INCLUDE
T}:T{
.sp
Include another dictionary file
T}
T{
.sp
MEMBER
T}:T{
.sp
Define a member of a \f(CRSTRUCT\fP
T}
T{
.sp
PROTOCOL
T}:T{
.sp
Define a protocol like \f(CRRADIUS\fP or \f(CRDHCPv4\fP
T}
T{
.sp
STRUCT
T}:T{
.sp
Define a structure which can contain \f(CRMEMBER\fPs
T}
T{
.sp
VALUE
T}:T{
.sp
Define a name for a particular value of an \f(CRATTRIBUTE\fP
T}
T{
.sp
VENDOR
T}:T{
.sp
Define a name and number for a vendor
T}
.TE
.sp
.sp
The following keywords define logical nesting of attributes.
.sp
.it 1 an-trap
.nr an-no-space-flag 1
.nr an-break-flag 1
.br
.B Table 2. Dictionary Nesting Keywords
.TS
allbox tab(:);
ltB ltB.
T{
.sp
BEGIN\-PROTOCOL
T}:T{
.sp
Begin defining a protocol dictionary
T}
.T&
lt lt.
T{
.sp
END\-PROTOCOL
T}:T{
.sp
End a protocol dictionary
T}
T{
.sp
BEGIN
T}:T{
.sp
Begin defining children of a structural data type
T}
T{
.sp
END
T}:T{
.sp
End defining children of a structural data type
T}
T{
.sp
BEGIN\-VENDOR
T}:T{
.sp
Begin defining vendor\-specific attributes
T}
T{
.sp
END\-VENDOR
T}:T{
.sp
End defining vendor\-specific attributes
T}
.TE
.sp
.SH "SEE ALSO"
.sp
radiusd(8) radiusd.conf(5)
.SH "AUTHOR"
.sp
The FreeRADIUS Server Project (\c
.URL "https://freeradius.org" "" ")"
.SH "AUTHOR"
.sp
Alan DeKok